Function            getget - get a string from the keyboard w/editing

  Syntax              int getget(int col, int row, char *returnstr,
                                 int size, char *pattern, int argn,
                                 int argk[], unsigned flags);

  Prototype in        keyboard.h

  Remarks             getget inputs a string at coordinates (col,row), of
                      maximum length size, formatted according to
                      pattern. Input ends when ENTER or one of the scan
                      codes specified in argk[] in inputted. There are
                      argn number of elements in argk[]. The string is
                      returned in returnstr and the function returns the
                      key code of the exiting key.

                      Full feature editing of the string includes:

                           Enter          Ends input, exits function
                           Backspace      normal backspace
                           Insert         toggle inset/overwrite mode
                           Delete         delete character under cursor
                           Left Arrow     move cursor back 1 character
                           Right Arrow    move cursor forward 1 character
                           Home           move cursor to beginning of
                                          string
                           End            move cursor to end of string
                           Ctrl-Y         delete entire string
                           Alt-Y          delete string from cursor to
                                          end
                           Ctrl-Right     move cursor to beginning of
                                          next word
                           Ctrl-Left      move cursor to beginning of
                                          previous word
                           Alt-U          undo editing - restore initial
                                          string

                      Here are the valid patterns:

                                 pattern     format
                                 -------     ------
                      Types          a       Alphabetic
                                     A       Alphabetic and capitalized
                                     D or d  Date
                                     f       DOS Filename
                                     F       DOS Filename and capitalized
                                     h       Hexadecimal
                                     H       Hexadecimal and capitalized
                                     n       Alphanumeric
                                     N       Alphanumeric and capitalized
                                     p       DOS Pathname
                                     P       DOS Pathname and capitalized
                                     X       Ascii (default)
                                     9       Numeric
                                     #       Numeric and punctuation

                      Modifiers      !       convert to upper case
                                     .       punctuation

                      The flags modifier is a bit field of flags, as
                      follows:

                           xxxxxxxx UDJJBLRI        where

                           U  = call _idle_get() after keyboard input
                           D  = free time slices under DESQview
                           JJ = Justify (left, right, center)
                           B  = Bell
                           L  = trim Left side on exit
                           R  = trim Right side on exit
                           I  = start edit in Insert mode (as opposed
                                to Overwrite mode)

                      Input is done via the inkeydv() function if the
                      DESQview free time slices flag is set, otherwise
                      inkey().

                      After input is polled, if the user defined function
                      flag is set (UDFIDLE) the function _idle_get is
                      called. Currently, the definition of _idle_get is:

                                int _idle_get(void)

                      Possible uses for such a function is an onscreen
                      clock, printing, or some other background task. In
                      the future _idle_get() will receive releveant
                      parameters from getget(). To define _idle_get as
                      the user defined function int myfunction(void),
                      try:

                           _idle_get = (far *)myfunction;

                      The full definition for _idle_get() is:

                           int (far *_idle_get)(void);

                      You should declare myfunction() as type int, with
                      void parameters, and you should typecast the
                      function as a far pointer when you assign it to
                      _idle_get.

                      Cursor sizes are determined via the global
                      variables _cursorinsert and _cursoroverwrite.

                      Video output is via Borland's console i/o.

  Return value        returns the key code of the key causing the exit

  See also            getstr(), inkey(), inkeydv()